From 3c906f86168a61ccb7439a14e94c16f76d1fdaaa Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 29 Dec 2008 00:07:32 +0000 Subject: [PATCH] Doc fixes 2008-12-28 Matthias Clasen * gtk/gtkimmodule.c: * gtk/gtkseparatortoolitem.c: Doc fixes * gtk/gtkfontsel.c: Merge docs inline. svn path=/trunk/; revision=21957 --- ChangeLog | 4 ++ gtk/gtkfontsel.c | 124 +++++++++++++++++++++---------------- gtk/gtkimmodule.c | 14 ++--- gtk/gtkseparatortoolitem.c | 18 +++--- 4 files changed, 90 insertions(+), 70 deletions(-) diff --git a/ChangeLog b/ChangeLog index dc48ea7d26..1378157ec0 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,9 @@ 2008-12-28 Matthias Clasen + * gtk/gtkimmodule.c: + * gtk/gtkseparatortoolitem.c: Doc fixes + + * gtk/gtkfontsel.c: * gtk/gtkeditable.c: Merge docs inline. 2008-12-28 Matthias Clasen diff --git a/gtk/gtkfontsel.c b/gtk/gtkfontsel.c index 949a371462..394744fd15 100644 --- a/gtk/gtkfontsel.c +++ b/gtk/gtkfontsel.c @@ -538,6 +538,13 @@ gtk_font_selection_init (GtkFontSelection *fontsel) gtk_widget_pop_composite_child(); } +/** + * gtk_font_selection_new: + * + * Creates a new #GtkFontSelection. + * + * Return value: a n ew #GtkFontSelection + */ GtkWidget * gtk_font_selection_new (void) { @@ -1129,10 +1136,10 @@ gtk_font_selection_get_font_internal (GtkFontSelection *fontsel) * This returns the #GtkTreeView that lists font families, for * example, 'Sans', 'Serif', etc. * - * Return value: A #GtkWidget. + * Return value: A #GtkWidget that is part of @fontsel * * Since: 2.14 - **/ + */ GtkWidget * gtk_font_selection_get_family_list (GtkFontSelection *fontsel) { @@ -1148,10 +1155,10 @@ gtk_font_selection_get_family_list (GtkFontSelection *fontsel) * This returns the #GtkTreeView which lists all styles available for * the selected font. For example, 'Regular', 'Bold', etc. * - * Return value: A #GtkWidget. + * Return value: A #GtkWidget that is part of @fontsel * * Since: 2.14 - **/ + */ GtkWidget * gtk_font_selection_get_face_list (GtkFontSelection *fontsel) { @@ -1167,10 +1174,10 @@ gtk_font_selection_get_face_list (GtkFontSelection *fontsel) * This returns the #GtkEntry used to allow the user to edit the font * number manually instead of selecting it from the list of font sizes. * - * Return value: A #GtkWidget. + * Return value: A #GtkWidget that is part of @fontsel * * Since: 2.14 - **/ + */ GtkWidget * gtk_font_selection_get_size_entry (GtkFontSelection *fontsel) { @@ -1185,10 +1192,10 @@ gtk_font_selection_get_size_entry (GtkFontSelection *fontsel) * * This returns the #GtkTreeeView used to list font sizes. * - * Return value: A #GtkWidget. + * Return value: A #GtkWidget that is part of @fontsel * * Since: 2.14 - **/ + */ GtkWidget * gtk_font_selection_get_size_list (GtkFontSelection *fontsel) { @@ -1203,10 +1210,10 @@ gtk_font_selection_get_size_list (GtkFontSelection *fontsel) * * This returns the #GtkEntry used to display the font as a preview. * - * Return value: A #GtkWidget. + * Return value: A #GtkWidget that is part of @fontsel * * Since: 2.14 - **/ + */ GtkWidget * gtk_font_selection_get_preview_entry (GtkFontSelection *fontsel) { @@ -1222,10 +1229,12 @@ gtk_font_selection_get_preview_entry (GtkFontSelection *fontsel) * Gets the #PangoFontFamily representing the selected font family. * * Return value: A #PangoFontFamily representing the selected font - * family. Font families are a collection of font faces. + * family. Font families are a collection of font faces. The + * returned object is owned by @fontsel and must not be modified + * or freed. * * Since: 2.14 - **/ + */ PangoFontFamily * gtk_font_selection_get_family (GtkFontSelection *fontsel) { @@ -1241,11 +1250,12 @@ gtk_font_selection_get_family (GtkFontSelection *fontsel) * Gets the #PangoFontFace representing the selected font group * details (i.e. family, slant, weight, width, etc). * - * Return value: A #PangoFontFace representing the selected font group - * details + * Return value: A #PangoFontFace representing the selected font + * group details. The returned object is owned by @fontsel and + * must not be modified or freed. * * Since: 2.14 - **/ + */ PangoFontFace * gtk_font_selection_get_face (GtkFontSelection *fontsel) { @@ -1260,8 +1270,8 @@ gtk_font_selection_get_face (GtkFontSelection *fontsel) * * The selected font size. * - * Return value: A #gint representing the font size selected, or -1 - * if not. + * Return value: A n integer representing the selected font size, + * or -1 if no font size is selected. * * Since: 2.14 **/ @@ -1277,10 +1287,12 @@ gtk_font_selection_get_size (GtkFontSelection *fontsel) * gtk_font_selection_get_font: * @fontsel: a #GtkFontSelection * + * Gets the currently-selected font. + * * Return value: A #GdkFont. * * Deprecated: 2.0: Use gtk_font_selection_get_font_name() instead. - **/ + */ GdkFont * gtk_font_selection_get_font (GtkFontSelection *fontsel) { @@ -1293,16 +1305,18 @@ gtk_font_selection_get_font (GtkFontSelection *fontsel) * gtk_font_selection_get_font_name: * @fontsel: a #GtkFontSelection * - * Gets the currently-selected font name. Note that this can be a different - * string than what you set with gtk_font_selection_set_font_name(), as - * the font selection widget may normalize font names and thus return a string - * with a different structure. For example, "Helvetica Italic Bold 12" could be - * normalized to "Helvetica Bold Italic 12". Use pango_font_description_equal() + * Gets the currently-selected font name. + * + * Note that this can be a different string than what you set with + * gtk_font_selection_set_font_name(), as the font selection widget may + * normalize font names and thus return a string with a different structure. + * For example, "Helvetica Italic Bold 12" could be normalized to + * "Helvetica Bold Italic 12". Use pango_font_description_equal() * if you want to compare two font descriptions. * - * Return value: A string with the name of the current font, or #NULL if no font - * is selected. You must free this string with g_free(). - **/ + * Return value: A string with the name of the current font, or %NULL if + * no font is selected. You must free this string with g_free(). + */ gchar * gtk_font_selection_get_font_name (GtkFontSelection *fontsel) { @@ -1327,14 +1341,16 @@ gtk_font_selection_get_font_name (GtkFontSelection *fontsel) * @fontsel: a #GtkFontSelection * @fontname: a font name like "Helvetica 12" or "Times Bold 18" * - * Sets the currently-selected font. Note that the @fontsel needs to know the - * screen in which it will appear for this to work; this can be guaranteed by - * simply making sure that the @fontsel is inserted in a toplevel window before - * you call this function. + * Sets the currently-selected font. + * + * Note that the @fontsel needs to know the screen in which it will appear + * for this to work; this can be guaranteed by simply making sure that the + * @fontsel is inserted in a toplevel window before you call this function. * - * Return value: #TRUE if the font could be set successfully; #FALSE if no such - * font exists or if the @fontsel doesn't belong to a particular screen yet. - **/ + * Return value: %TRUE if the font could be set successfully; %FALSE if no + * such font exists or if the @fontsel doesn't belong to a particular + * screen yet. + */ gboolean gtk_font_selection_set_font_name (GtkFontSelection *fontsel, const gchar *fontname) @@ -1440,13 +1456,12 @@ gtk_font_selection_set_font_name (GtkFontSelection *fontsel, * gtk_font_selection_get_preview_text: * @fontsel: a #GtkFontSelection * - * The text returned is the preview text used to show how the selected - * font looks. + * Gets the text displayed in the preview area. * - * Return value: pointer to the preview text string. This string - * points to internally allocated storage in the widget and must not - * be freed, modified or stored. - **/ + * Return value: the text displayed in the preview area. + * This string is owned by the widget and should not be + * modified or freed + */ G_CONST_RETURN gchar* gtk_font_selection_get_preview_text (GtkFontSelection *fontsel) { @@ -1459,10 +1474,11 @@ gtk_font_selection_get_preview_text (GtkFontSelection *fontsel) /** * gtk_font_selection_set_preview_text: * @fontsel: a #GtkFontSelection - * @text: a pointer to a string + * @text: the text to display in the preview area * + * Sets the text displayed in the preview area. * The @text is used to show how the selected font looks. - **/ + */ void gtk_font_selection_set_preview_text (GtkFontSelection *fontsel, const gchar *text) @@ -1655,16 +1671,18 @@ gtk_font_selection_dialog_buildable_get_internal_child (GtkBuildable *buildable, * gtk_font_selection_dialog_get_font_name: * @fsd: a #GtkFontSelectionDialog * - * Gets the currently-selected font name. Note that this can be a different - * string than what you set with gtk_font_selection_dialog_set_font_name(), as - * the font selection widget may normalize font names and thus return a string - * with a different structure. For example, "Helvetica Italic Bold 12" could be - * normalized to "Helvetica Bold Italic 12". Use pango_font_description_equal() + * Gets the currently-selected font name. + * + * Note that this can be a different string than what you set with + * gtk_font_selection_dialog_set_font_name(), as the font selection widget + * may normalize font names and thus return a string with a different + * structure. For example, "Helvetica Italic Bold 12" could be normalized + * to "Helvetica Bold Italic 12". Use pango_font_description_equal() * if you want to compare two font descriptions. * - * Return value: A string with the name of the current font, or #NULL if no font - * is selected. You must free this string with g_free(). - **/ + * Return value: A string with the name of the current font, or %NULL if no + * font is selected. You must free this string with g_free(). + */ gchar* gtk_font_selection_dialog_get_font_name (GtkFontSelectionDialog *fsd) { @@ -1698,7 +1716,7 @@ gtk_font_selection_dialog_get_font (GtkFontSelectionDialog *fsd) * Sets the currently selected font. * * Return value: %TRUE if the font selected in @fsd is now the - * @fontname specified. %FALSE otherwise. + * @fontname specified, %FALSE otherwise. */ gboolean gtk_font_selection_dialog_set_font_name (GtkFontSelectionDialog *fsd, @@ -1718,8 +1736,8 @@ gtk_font_selection_dialog_set_font_name (GtkFontSelectionDialog *fsd, * font looks. * * Return value: pointer to the preview text string. This string - * points to internally allocated storage in the widget and must not - * be freed, modified or stored. + * points to internally allocated storage in the widget and must not + * be freed, modified or stored. */ G_CONST_RETURN gchar* gtk_font_selection_dialog_get_preview_text (GtkFontSelectionDialog *fsd) @@ -1733,7 +1751,7 @@ gtk_font_selection_dialog_get_preview_text (GtkFontSelectionDialog *fsd) * gtk_font_selection_dialog_set_preview_text: * @fsd: a #GtkFontSelectionDialog * @text: a pointer to a string - + * * The @text is used to show how the selected font looks. */ void diff --git a/gtk/gtkimmodule.c b/gtk/gtkimmodule.c index 125f685e63..b347abd4f2 100644 --- a/gtk/gtkimmodule.c +++ b/gtk/gtkimmodule.c @@ -55,10 +55,8 @@ * GtkIMContextInfo: * @context_id: The unique identification string of the input method. * @context_name: The human-readable name of the input method. - * @domain: Translation domain to be used with - * dgettext(). - * @domain_dirname: Name of locale directory for use with - * bindtextdomain(). + * @domain: Translation domain to be used with dgettext() + * @domain_dirname: Name of locale directory for use with bindtextdomain() * @default_locales: A colon-separated list of locales where this input method * should be the default. The asterisk "*" sets the default for all locales. * @@ -513,7 +511,7 @@ compare_gtkimcontextinfo_name(const GtkIMContextInfo **a, * @n_contexts: the length of the array stored in @contexts * * List all available types of input method context - **/ + */ void _gtk_im_module_list (const GtkIMContextInfo ***contexts, guint *n_contexts) @@ -591,8 +589,8 @@ _gtk_im_module_list (const GtkIMContextInfo ***contexts, * ID @context_id. * * Return value: a newly created input context of or @context_id, or - * if that could not be created, a newly created GtkIMContextSimple. - **/ + * if that could not be created, a newly created GtkIMContextSimple. + */ GtkIMContext * _gtk_im_module_create (const gchar *context_id) { @@ -660,7 +658,7 @@ match_locale (const gchar *locale, * for the given window. * * Return value: the context ID (will never be %NULL) - **/ + */ const gchar * _gtk_im_module_get_default_context_id (GdkWindow *client_window) { diff --git a/gtk/gtkseparatortoolitem.c b/gtk/gtkseparatortoolitem.c index 52af0df8b2..4aa4b15697 100644 --- a/gtk/gtkseparatortoolitem.c +++ b/gtk/gtkseparatortoolitem.c @@ -221,7 +221,7 @@ gtk_separator_tool_item_expose (GtkWidget *widget, * Return value: the new #GtkSeparatorToolItem * * Since: 2.4 - **/ + */ GtkToolItem * gtk_separator_tool_item_new (void) { @@ -237,13 +237,13 @@ gtk_separator_tool_item_new (void) * gtk_separator_tool_item_get_draw: * @item: a #GtkSeparatorToolItem * - * Returns whether @separator_tool_item is drawn as a - * line, or just blank. See gtk_separator_tool_item_set_draw(). + * Returns whether @item is drawn as a line, or just blank. + * See gtk_separator_tool_item_set_draw(). * - * Return value: #TRUE if @separator_tool_item is drawn as a line, or just blank. + * Return value: %TRUE if @item is drawn as a line, or just blank. * * Since: 2.4 - **/ + */ gboolean gtk_separator_tool_item_get_draw (GtkSeparatorToolItem *item) { @@ -255,14 +255,14 @@ gtk_separator_tool_item_get_draw (GtkSeparatorToolItem *item) /** * gtk_separator_tool_item_set_draw: * @item: a #GtkSeparatorToolItem - * @draw: whether @separator_tool_item is drawn as a vertical line + * @draw: whether @item is drawn as a vertical line * - * When @separator_tool_items is drawn as a vertical line, or just blank. - * Setting this #FALSE along with gtk_tool_item_set_expand() is useful + * Whether @item is drawn as a vertical line, or just blank. + * Setting this to %FALSE along with gtk_tool_item_set_expand() is useful * to create an item that forces following items to the end of the toolbar. * * Since: 2.4 - **/ + */ void gtk_separator_tool_item_set_draw (GtkSeparatorToolItem *item, gboolean draw) -- 2.30.2